home *** CD-ROM | disk | FTP | other *** search
/ Hottest 6 / Hottest 6 (1996)(PDSoft)[!].iso / software / programming / c / shadow / docs / compatibility.doc next >
Text File  |  1978-11-24  |  9KB  |  196 lines
  1.                        Shadow Development Documentation
  2.                             Library Version 5.0
  3.  
  4.                               By David Navas
  5.                          Updated:  13 Nov 1992
  6.  
  7.                       Copyright © 1992 by David Navas
  8.                             All Rights Reserved
  9.  
  10.  
  11.                                 COMPATIBILITY
  12.  
  13.      This document is only required for those upgrading from V4.  Anyone
  14.      who has not programmed SHADOW under V4 should not need to read this
  15.      document.  Anyone who has V4 files on disk should delete them
  16.      -right- -now-!  Anyone who has programmed any apps using shadow 4
  17.      must read this document in its entirety.
  18.  
  19.      Please note that this includes the example demo modules on the WEB
  20.      Data Acq. and Analysis demo distribution disk.  This demo will NOT
  21.      run correctly and may CRASH your machine.  A new demonstration disk
  22.      will be available ASAP.
  23.  
  24.      Several things have changed in V5 since V4.  The most significant of
  25.      these changes is to PROCESS_CLASS.  The following library calls are
  26.      no longer available, required, or supported:
  27.           WaitThread()
  28.           InitThread()
  29.           RemoveThread()
  30.  
  31.      Their features have been swallowed up by the new method calls within
  32.      SHADOW itself.  However, it is extremely unlikely that anyone has
  33.      created a subclass of PROCESS_CLASS, so this will not directly affect
  34.      anyone.  If you have, please call me at (415) 591-2907, and we will
  35.      discuss how you need to alter your code to get the desired results.
  36.  
  37.      What this does affect, however, is the initialization method for the
  38.      PROCESS_CLASS itself.  If you have ever created a process -object-
  39.      using either:
  40.           procObject = CreateInstance(NULL, PROCESSCLASS, METACLASS,
  41.                                                           .
  42.                                                           .
  43.                                                           .
  44.                                                           METHOD_END);
  45.           -or-
  46.  
  47.           ProcClass = FindJazzClass(PROCESSCLASS);
  48.           procObj = DoJazzMethod(ProcClass, NULL, METHOD_META_CREATE,
  49.                                                   METHOD_END);
  50.           procObj = DoJazzMethod(procObj, NULL, METHOD_META_INIT,
  51.                                                 .
  52.                                                 .
  53.                                                 .
  54.                                                 METHOD_END);
  55.  
  56.      then you need to pay very close attention!
  57.  
  58.      The METHOD_META_INIT (now and hereafter in this document to be
  59.      referred to by its SHADOW V name, METH_INIT) takes the following
  60.      arguments in the following order:
  61.  
  62.           JSTR -- name of the process to create.
  63.           JOBJ -- The parent object.  If no parent object, the
  64.                    calling process is used as the parent.
  65.           SEMF -- an optional semaphore to own shared by the started
  66.                    process.  Semaphore is Release()'d when task exits.
  67.           TAGL -- a NULL terminated array of struct TagItem to send to
  68.                    the CreateNewProc invok.  If the INIT fails AFTER
  69.                    the process is created, the tags' ti_Tag are set
  70.                    to TAG_IGNORE, so you don't have to free the
  71.                    resources that might be in the TAGL if the process
  72.                    fails to be created.  (In fact, the ti_Tags are
  73.                    set to TAG_IGNORE even if the process successfully
  74.                    opens.)
  75.           APTR -- Pointer to an optional ProcessInitFrame.  This is
  76.                    used as an override array to the ASSOCIATE method
  77.                    to allow the METH_INIT to initialize other classes
  78.                    of processes in an arbitrarily coplex manner.
  79.           APTR -- Pointer to an optional ProcessHandlerFrame.  This is
  80.                    used as an override array to the HANDLER method
  81.                    to allow METH_INIT to initialize other classes of
  82.                    processes in an arbitrarily complex manner.
  83.  
  84.      The last two arguments were never used by SHADOW 4, and may remain
  85.      NULL for the default configuration.  Specifying the parent process
  86.      object as your program's process object is the preferred way to
  87.      deal with thread/parent shutdown problems.  Previous to this
  88.      version, a semaphore was used instead.  While this is still
  89.      supported, it is highly recommended that you use the parent object
  90.      instead.  Also, please note, to increase compatibility between new
  91.      and old releases, you may not specify both the SEMF and the JOBJ
  92.      parameters.  Pick one or the other, but not both.
  93.  
  94.      There is no parameter for the threadStart() function.  The default
  95.      threadStart is -always- used.  Please read the PROCESS_CLASS
  96.      description in Introduction.doc (the last topic in that file!) for
  97.      more details on how to customize process startups.
  98.  
  99.      The taglist is the same parameter it has always been (though it might
  100.      be in a different place in the argument list!).
  101.  
  102.      Please reorganize ANY process object creation code you had NOW!
  103.  
  104.  
  105.      ----
  106.  
  107.  
  108.      There have been a great number of other changes in SHADOW, mostly
  109.      additions and further fleshing out of some of the feature set.  Most
  110.      importantly, 500k of documentation is included with this release, so
  111.      I suggest you start reading Introduction.doc now (before your brain
  112.      registers that 500k == 250 pages).
  113.  
  114.      Most of the differences between old code and new code is the
  115.      large number of name changes.  These have been made to remove some
  116.      naming inconsistencies, and to remove the word "JAZZ" from a product
  117.      which is now called "SHADOW."
  118.  
  119.      To fix the former problem, names like:
  120.           AddNodeBinTree() and RemoveBinNode()
  121.  
  122.      have been unified into:
  123.           AddTreeNode(), RemoveTreeNode()
  124.  
  125.      To fix the latter problem, names like:
  126.           ATTR_JAZZPROCESS and DoJazzMethod()
  127.  
  128.      have been changed to:
  129.           ATTR_SHADOWPROCESS and DoShadow()
  130.  
  131.  
  132.      A compatibility include file is included in the development release
  133.      which will allow you to continue to use the old naming and drift
  134.      slowly to the new names.  In addition, the new misc.h include file
  135.      will automatically include this file if the macro symbol
  136.      "SHADOW_4_CONVERT" is declared before misc.h is included....
  137.  
  138.      The include file is named shadow4convert.h, and I suggest you
  139.      actually read through the file to see all of the name changes
  140.      (there are quite a few).
  141.  
  142.      In addition to these minor name changes, a number of symbols and flag
  143.      values have changed as well.  Recompiling with the new includes will
  144.      fix most of these problems, however, this means that it is
  145.      -impossible- to run the your old compiled programs with the new
  146.      SHADOW!  A recompile is -absolutely- -necessary-.
  147.  
  148.      There are three more changes which you will not be able to fix by mere
  149.      recompilation.  The first is that MethodFuncParse()'s argument list
  150.      has changed (it takes an additional parameter which you should
  151.      set to zero), and the argument order has been changed to increase
  152.      the efficiency of the glue code for DICE.  Please note that you
  153.      probably have never used MethodFuncParse()!
  154.  
  155.      Also, the METHOD_FLAG_RTRN_ME flag no longer exists.  The bit that
  156.      it used to use has had its meaning inverted.  Thus, you can now
  157.      define methods that no longer have return values, as well as
  158.      patches that have no return values.  Use METH_FLAG_NO_RTRN for
  159.      methods and patches that have no return values.  For patches that
  160.      do have return values, you may leave this bit unset -- there is
  161.      no need for METHOD_FLAG_RTRN_ME.  As always, for methods, you may
  162.      leave this bit unset for methods that return values....
  163.  
  164.      Lastly, if you ever used 'MRFO' for passing data in objects around,
  165.      the entry has gotten more functionality, but grown incompatible.
  166.      for any method arguments that were MRFOs, please change the
  167.      METHOD_REF (now referred to as ARGUMENT_TAGs) from:
  168.           {'MRFO, 4, 0}
  169.      to:
  170.           {'MRFO', 4, 8}
  171.         -or-
  172.           ARG_MRFO(8)         <-- preferred
  173.  
  174.      You can now pass pointers to data within objects by letting the
  175.      third field in the ARGUMENT_TAG (or the argument within the definition
  176.      macro ARG_MRFO) be the offset of the data from the start of the
  177.      object.  This allows the object to be correctly resource tracked
  178.      and not copied when sending the data asynchronously.  This is most
  179.      useful for sending data within ClasslessObjects, where the data
  180.      starts from an offset of 12, instead of 8 as in normal objects....
  181.  
  182.  
  183.  
  184.      SHADOW V is considered the full production release of SHADOW.  As
  185.      such, future changes like SHADOW 4 --> SHADOW V will be avoided at
  186.      all costs to allow you to create real commercial programs without the
  187.      hassle of recompiling and backwards compatibilty issues.  However,
  188.      these changes were necessary to facilitate the release of a
  189.      production version, as many of the naming schemes were incoherent or
  190.      just plain incorrect.
  191.  
  192.      Thanks for using SHADOW, and I hope the upgrade goes as smoothly for
  193.      you as it did for my own commercial apps!
  194.  
  195.                                                   Dave Navas
  196.